<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Horde3D Documentation</title>
    <link rel="stylesheet" type="text/css" href="css/manual.css" title="ALL" media="screen,projection" />
</head>

<body>
<div id="content">

<a id="Content"></a>
<h1>Horde3D Content Pipeline</h2>

<h2>Overview</h2>

<p>The content pipeline is responsible for bringing game assets (i.e. models, animations, textures, etc.) from a digital content creation (DCC)
tool into the running game. The general content pipeline of Horde3D has three stages. Artists create assets in their preferred DCC application,
for example Blender or 3D Studio Max. These source assets are exported into a standardized intermediate format using an exporter plugin that
is available for the DCC tool. From the intermediate format, an optimized runtime format is generated using a special compiler that is part of
the Horde3D package. This final runtime format conversion can usually be performed automatically in a content build process.</p>

<p>Generating the runtime data from an intermediate format brings some advantages over directly exporting the assets into the final format. An
obvious benefit is that the  runtime format can be changed and optimized without the need to manually reexport all assets. Furthermore, different
platforms may require a slightly different representation of the same data (e.g. little endian vs. big endian). With an automated content build
process, some special processing can be performed specifically for each platform which can lead to greatly reduced loading times.</p>

<p>It is highly recommended to store not only the original DCC application source files but also the intermediate files in some sort of database or
revision control system, so that the runtime data can be regenerated at any time. Storing the runtime data in a version control system is usually
not required, as it can always be generated again, for example automatically in a nightly build process.</p>

<h2>Models and Animations</h2>

<p>For models and animations, Horde3D uses COLLADA 1.4 as intermediate format. Artists export their models using an appropriate COLLADA exporter
that comes with the DCC package or is available as a separate plugin. The tool ColladaConv which comes with Horde3D can be used to compile
the data to the optimized runtime format expected by the Horde3D engine.</p>

<h3>Using ColladaConv</h3>

<p>ColladaConv is a command line tool which means that it can easily be used in a more complex build process. When running ColladaConv, the first
command line argument which is expected is an input file or directory. If a directory is specified, ColladaConv will recursively process all
subdirectories as well and recreate the same directory structure for the output. To process all files in the repository, a single dot can be
used as input parameter.</p>

<p>ColladaConv works in passes when generating the runtime asset data, so one resource type is processed at a time. This means that you can run
ColladaConv first for compiling all models and after that for processing all animations. The resource type to be converted is specified with
the command line argument <b>-type</b>. </p>

<p>With the argument <b>-base</b>, it is possible to specify the base content directory (repository) where the intermediate source assets are located.
All resource paths generated by ColladaConv will be relative to that base directory. The argument <b>-dest</b> is used to specify the output directory
to which all files generated by ColladaConv will be written.</p>

<p>Materials are often modified by hand or with a scene editor, so it is usually not desired that they get overwritten automatically. For that
reason, ColladaConv will not overwrite existing materials, except it is forced to do so with the command line argument <b>-overwriteMats</b>.</p>

<p><b>Examples:</b>
<div class="codebox"><pre>
ColladaConv models/man/man.dae -base C:\MyRepository -dest C:\MyContent -type model
ColladaConv animations -base C:\MyRepository -dest C:\MyContent -type anim
</pre></div></p>

<p>The first command line above will compile the model <i>man.dae</i>. It is expected that the asset is located in <i>C:\MyRepository\models\man</i>.
The generated files will be written to <i>C:\MyContent\models\man</i>. As all resource paths are relative to the base folder and do not contain
absolute paths, the destination directory could always be renamed or relocated later without breaking any references.</p>

<p>The second command line will process the directory <i>C:\MyRepository\animations</i> and compile all DAE files which are located in that directory,
including the ones which are in subdirectories. The exact same subdirectory structure will be created by ColladaConv in the destination folder.
So for example, if the input folder contains a file <i>animations/human/walk.dae</i>, ColladaConv will create the file <i>C:\MyContent\animations\human\walk.anim</i>.
It is hence possible to compile the whole (animation) repository with a single ColladaConv call.</p>

<h3>Command Line Arguments</h3>
<p>The following is a list of all supported command line arguments. All arguments are optional, except for the input which always has to be the
first argument.</p>
<div class="descbox">
<table>
    <tr>
        <td><b>input</b></td>
        <td>asset file or directory to be processed; use . to process all files and subfolders in the base directory (required)</td>
    </tr>
	<tr>
        <td><b>-type <i>model</i>|<i>anim</i></b></td>
        <td>asset type to be processed; can be <b>model</b> (default) or <b>anim</b></td>
    </tr>
	<tr>
        <td><b>-base</b> <i>path</i></td>
        <td>base path where the repository root is located; all generated paths will be relative to the base directory</td>
    </tr>
	<tr>
        <td><b>-dest</b> <i>path</i></td>
        <td>destination path to which compiled assets are output (path must exist)</td>
    </tr>
    <tr>
        <td><b>-noGeoOpt</b></td>
        <td>disables geometry optimization</td>
    </tr>
	<tr>
        <td><b>-addModelName</b></td>
        <td>adds model name before material name</td>
    </tr>
	<tr>
        <td><b>-overwriteMats</b></td>
        <td>forces update of existing materials</td>
    </tr>
	<tr>
        <td><b>-lodDist1</b> <i>dist</i></td>
        <td>distance for LOD1 (default: 10)</td>
    </tr>
	<tr>
        <td><b>-lodDist2</b> <i>dist</i></td>
        <td>distance for LOD2 (default: 20)</td>
    </tr>
	<tr>
        <td><b>-lodDist3</b> <i>dist</i></td>
        <td>distance for LOD3 (default: 40)</td>
    </tr>
	<tr>
        <td><b>-lodDist4</b> <i>dist</i></td>
        <td>distance for LOD4 (default: 80)</td>
    </tr>
</table>
</div>

<h3>LOD Support</h3>
<p>The converter has support for discrete level of detail (LOD) meshes. By default, a mesh is considered as base LOD (LOD0).
To define simplified LODs, a special naming convention is used. Use the postfixes <b>_lod1</b>, <b>_lod2</b>,
<b>_lod3</b> or <b>_lod4</b> at the end of a mesh name to define the corresponding LOD level. The converter will
automatically remove the postfix from the name and assign the specified LOD level to the output mesh. The command
line arguments lodDist1 to lodDist4 can be used to define the distances from which on a detail level is activated.</p>

<h3>Important Notes</h3>
<p>At the moment there are some restrictions for COLLADA files to be compatible with the converter:
All geometry should be stored as triangle data and animations have to be exported as sampled keyframe data.</p>


<h2>Textures</h2>
<p>At the moment, Horde3D does not provide a conditioning pipeline for textures. Textures are directly loaded by the engine
from one of the supported image formats.</p>

</body>
</html>
